Crate poem_openapi

OpenAPI support for Poem.

Poem-openapi allows you to easily implement APIs that comply with the OpenAPIv3 specification. It uses procedural macros to generate a lots of boilerplate code, so that you only need to focus on the more important business implementations.

Table of contents

• Features
• Quickstart
• Crate features

Features

• Type safety If your codes can be compiled, then it is fully compliant with the OpenAPI v3 specification.
• Rustfmt friendly Do not create any DSL that does not conform to Rust’s syntax specifications.
• IDE friendly Any code generated by the procedural macro will not be used directly.
• Minimal overhead All generated code is necessary, and there is almost no overhead.

Quickstart

Cargo.toml

[package]
name = "helloworld"
version = "0.1.0"
edition = "2021"

[dependencies]
poem = "1.2"
poem-openapi = { version = "1.2", features = ["swagger-ui"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

main.rs

use poem::{listener::TcpListener, Route, Server};
use poem_openapi::{payload::PlainText, OpenApi, OpenApiService};

struct Api;

#[OpenApi]
impl Api {
    /// Hello world
    #[oai(path = "/", method = "get")]
    async fn index(&self) -> PlainText<&'static str> {
        PlainText("Hello World")
    }
}

#[tokio::main]
async fn main() {
    let api_service =
        OpenApiService::new(Api, "Hello World", "1.0").server("http://localhost:3000");
    let ui = api_service.swagger_ui();
    let app = Route::new().nest("/", api_service).nest("/docs", ui);

    Server::new(TcpListener::bind("127.0.0.1:3000"))
        .run(app)
        .await;
}

Check it

Open your browser at http://127.0.0.1:3000.

You will see the plaintext response as:

Hello World

Interactive API docs

Now go to http://127.0.0.1:3000/docs.

You will see the automatic interactive API documentation (provided by Swagger UI):

Crate features

To avoid compiling unused dependencies, Poem gates certain features, some of which are disabled by default:

Feature	Description
chrono	Integrate with the chrono crate.
time	Integrate with the time crate.
humantime	Integrate with the humantime crate
openapi-explorer	Add OpenAPI Explorer support
swagger-ui	Add swagger UI support
rapidoc	Add RapiDoc UI support
redoc	Add Redoc UI support
email	Support for email address string
hostname	Support for hostname string
humantime	Integrate with the humantime crate
uuid	Integrate with the uuid crate
url	Integrate with the url crate
geo	Integrate with the geo-types crate
bson	Integrate with the bson crate
rust_decimal	Integrate with the rust_decimal crate
prost-wkt-types	Integrate with the prost-wkt-types crate
static-files	Support for static file response
websocket	Support for websocket

Modules

• auth
  Some certificate types for security scheme.
• error
  Some common error types.
• macros
  Macros to help with building custom payload types.
• param
  Parameter types for the API operation.
• payload
  Commonly used payload types.
• types
  Commonly used data types.

Macros

• impl_apirequest_for_payload
  This macro implements ApiExtractor for your type, with additional bounds if you want to.

Structs

• ContactObject
  A contact information for the exposed API.
• ExternalDocumentObject
  An object representing a external document.
• ExtraHeader
  An extra header
• ExtractParamOptions
  Options for the parameter extractor.
• LicenseObject
  A license information for the exposed API.
• OpenApiService
  An OpenAPI service for Poem.
• OperationId
  A operation id that can be obtained from the response
• ServerObject
  An object representing a Server.

Enums

• ApiExtractorType
  API extractor types.

Traits

• ApiExtractor
  Represents a OpenAPI extractor.
• ApiResponse
  Represents a OpenAPI responses object.
• OAuthScopes
  Represents a OAuth scopes.
• OpenApi
  Represents a OpenAPI object.
• ResponseContent
  Represents a OpenAPI response content object.
• Tags
  Represents a OpenAPI tags.
• Validator
  Represents a validator for validate the input value.
• Webhook
  Represents a webhook object.

Attribute Macros

• OpenApi
  Define a OpenAPI.
• Webhook
  Define a OpenApi webhooks.

Derive Macros

• ApiRequest
  Define a OpenAPI request.
• ApiResponse
  Define a OpenAPI response.
• Enum
  Define a OpenAPI enum
• Multipart
  Define a OpenAPI payload.
• NewType
  Define a new type.
• OAuthScopes
  Define a OAuth scopes.
• Object
  Define a OpenAPI object
• ResponseContent
  Define a OpenAPI response content.
• SecurityScheme
  Define a OpenAPI Security Scheme.
• Tags
  Define a OpenAPI Tags.
• Union
  Define a OpenAPI discriminator object.